home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…stman Always Clicks Twice / ADC Developer CD (1993-01) (''The Postman Always Clicks Twice'')_iso / Dev.CD 199301.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.025 < prev    next >
Encoding:
Text File  |  1992-07-15  |  16.3 KB  |  415 lines  |  [TEXT/GEOL]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. Apple IIgs
  6. #25: Apple IIgs Firmware Reference Updates
  7.  
  8. Revised by: Dave Lyons                                               May 1992
  9. Written by: Rilla Reynolds, Dave Lyons         October 1987 to September 1990
  10.             & Jim Luther
  11.  
  12. This Technical Note includes updates to the May 1987 edition of the Apple IIgs
  13. Firmware Reference, published by Addison-Wesley (Part Number 030-3121-A).  The
  14. new Monitor commands require an Apple IIgs revised ROM (Part Number
  15. 342-0077-B), which is available without charge from an authorized Apple
  16. dealer.  Please contact Apple II Developer Technical Support at the address
  17. listed in Apple II Technical Note #0 if you have additional corrections or
  18. suggestions for this manual.
  19.  
  20. CHANGES SINCE SEPTEMBER 1990:  Added a reference to Apple IIgs Technical Note
  21. #102 for TOBRAMSETUP.
  22. _____________________________________________________________________________
  23.  
  24.  
  25. CONTENTS
  26.  
  27.    Page vii, Chapter 7  SmartPort Firmware:  Change "Generic SmartPort calls
  28.    121" to "Standard and Extended SmartPort calls   121."
  29.  
  30.  
  31. CHAPTER 2:  NOTES FOR PROGRAMMERS
  32.  
  33.    Page 11, Environment for the Firmware Routines:  Refer to Apple IIgs
  34.    Technical Note #88, The Page One Stack in a 16-Bit World for more
  35.    information on manipulating the stack pointer.
  36.  
  37.  
  38. CHAPTER 3:  SYSTEM MONITOR FIRMWARE
  39.  
  40.    Page 24, Table 3-1 (continued), Monitor commands grouped by type:  Add a
  41.    miscellaneous-type and a debugging-type Monitor command to the table, as
  42.    follows:
  43.  
  44.    Command type                                             Command format
  45.    -----------------------------------------------------------------------
  46.    ...
  47.    Quit Monitor                                             Q
  48.    Install Visit Monitor and MemoryPeeker desk accessories  #
  49.    ...
  50.    Enter mini-assembler                                     !
  51.    Set flags (e, m, x) for full-native mode                 Control-N
  52.    -----------------------------------------------------------------------
  53.  
  54.    Page 43, Back to BASIC:  The last paragraph should read:  "If you are
  55.    using DOS 3.3 or ProDOS(R), use the Monitor Q (Quit) command to return to
  56.    the language you were using with your program and variables intact."
  57.  
  58.  
  59.    Page 48, Table 3-6, Commands for program execution and debugging:  Add a
  60.    Monitor command to the table:
  61.  
  62.  
  63.    Command type                                             Command format
  64.    -----------------------------------------------------------------------
  65.    ...
  66.    Enter mini-assembler                                     !
  67.    Set flags (e, m, x) for full-native mode                 Control-N
  68.    -----------------------------------------------------------------------
  69.  
  70.    Page 66, after final paragraph:  Add a new Monitor instruction heading and
  71.    description:
  72.  
  73.  
  74.       NATIVE MODE SET CONTROL-N (NATIVE MODE)
  75.  
  76.       Control-N sets the m, x, e flags to 0 for full-native mode.  All other
  77.       registers are unchanged.
  78.  
  79.    Page 67, after final paragraph:  Add a new Monitor instruction heading and
  80.    description:
  81.  
  82.  
  83.       TURN ON ROM DESK ACCESSORIES, #
  84.  
  85.       Enables the currently available ROM desk accessories, Visit Monitor and
  86.       Memory Peeker.  These desk accessories remain active in the desk
  87.       accessory menu until power is shut off.  Control-Open Apple-Reset has
  88.       no affect on these items.  To exit the Visit Monitor desk accessory,
  89.       press Control-Y then press Return.  To exit the Memory Peeker desk
  90.       accessory, press Q.
  91.  
  92.  
  93. CHAPTER 4:  VIDEO FIRMWARE
  94.  
  95.    Page 77, Table 4-4, Control characters with 80-column firmware on:  Change
  96.    the actions taken by Control-E and Control-F to read (they were reversed):
  97.  
  98.  
  99.  
  100.       Control character                 Action taken by C3COUT1
  101.       ---------------------------------------------------------
  102.       Control-E                         Turns cursor on
  103.       Control-F                         Turns cursor off
  104.       ---------------------------------------------------------
  105.  
  106.  
  107. CHAPTER 5:  SERIAL-PORT FIRMWARE
  108.  
  109.    Page 82, Compatibility:  The second half of the third sentence in the
  110.    first paragraph should read:  "...the Apple IIgs hardware is different
  111.    from that used on the SSC."
  112.  
  113.  
  114.    Page 91, Input buffering, BE and BD:  This heading should be "Input/Output
  115.    buffering, BE and BD."
  116.  
  117.  
  118.    Page 94, Table 5-6:  The Extended Interface footnote which states, "If the
  119.    function call returns with the carry bit set..." is incorrect.  For Apple
  120.    IIgs ROM 01, the Extended Serial Interface does not return the error
  121.    condition in the carry bit.  Programs using the Extended Serial Interface
  122.    should check for a non-zero result value in the result code rather than
  123.    the carry bit to determine if an error has occurred.  For additional error
  124.    handling information using the Extended Interface, see Apple IIgs
  125.    Technical Note #50, Extended Serial Interface Error Handling.
  126.  
  127.  
  128.    Page 95, Error handling:  The second sentence should read:  "If the
  129.    character has a framing or parity error (assuming that the parity option
  130.    is not set to None), the character is deleted from the input stream and
  131.    the appropriate mode bit is set."
  132.  
  133.  
  134.    Page 96, Note:  The Note should read:  "The InQStatus elapsed-time counter
  135.    functions correctly only if a heartbeat interrupt task has been started.
  136.    A heartbeat interrupt task is a set of functions called by interrupt code
  137.    that run automatically at one-thirtieth of a second intervals.
  138.  
  139.  
  140.    Page 96, Interrupt notification:  The fourth sentence in the first
  141.    paragraph should be:  "The system interrupt handler will transfer control
  142.    to the user's interrupt vector at $03FE in bank $00."
  143.  
  144.  
  145.  
  146.    Page 97, Interrupt notification:  The last three paragraphs should be
  147.    replaced with this paragraph:  "The interrupt completion routine executes
  148.    as part of the firmware interrupt handler and must be run in that
  149.    environment.  The interrupt completion routine must preserve the DBR,
  150.    speed, 8-bit native mode, D register, stack pointer (or just use the
  151.    current stack), and MSLOT for proper operation. A/X/Y need not be
  152.    preserved."
  153.  
  154.  
  155.    Page 100, SetModeBits:  The first sentence in the paragraph following the
  156.    CMDLIST should read:  "Use this call to alter any of the mode bits whose
  157.    function is described below."
  158.  
  159.  
  160.    Page 105, GetIntInfo:  The command list should read:
  161.  
  162.  
  163.    CMDLIST    DFB    $03                   ;Parameter count
  164.               DFB    $0C                   ;Command code
  165.               DW     $00                   ;result code (output)
  166.               DW     $00                   ;interrupt setting (output)
  167.               DL     Completion address    ;(output)
  168.  
  169.    The following should be added after the command list:  "Note:  The
  170.    Parameter count of $03 is correct even though there are four parameters."
  171.  
  172.  
  173.    The following should be added after the last paragraph:  "Note:  Before
  174.    making this call from an interrupt completion routine, you must set the
  175.    operating environment to look and act exactly like a 6502 in all respects.
  176.    During interrupt completion routines, you must preserve the DBR, speed,
  177.    8-bit native mode, D register, stack pointer (or just use the current
  178.    stack), and MSLOT for proper operation.  A/X/Y need not be preserved.  See
  179.    "Environments for the Firmware Routines" in chapter 2, Notes for
  180.    Programmers for details about setting and restoring the operating
  181.    environment.
  182.  
  183.  
  184.    Page 106, SetIntInfo:  The command list should read:
  185.  
  186.  
  187.  
  188.  
  189.    CMDLIST    DFB    $03                   ;Parameter count
  190.               DFB    $0D                   ;Command code
  191.               DW     $00                   ;result code (output)
  192.               DW     Interrupt setting     ;(input)
  193.               DL     Completion address    ;(input)
  194.  
  195.    The following should be added after the command list, "Note:  The
  196.    Parameter count of $03 is correct even though there are four parameters."
  197.  
  198.  
  199.  
  200. CHAPTER 7:  SMARTPORT FIRMWARE
  201.  
  202.    Page 120, Issuing a call to SmartPort:  The standard and extended
  203.    SmartPort call examples should be:
  204.  
  205.  
  206.    This is an example of a standard SmartPort call:
  207.  
  208.  
  209.    SP_CALL        JSR    DISPATCH          ;Call SmartPort command dispatcher
  210.                   DC     i1'CMDNUM'        ;This specifies the command type
  211.                   DC     i2'CMDLIST'       ;Word ptr to param list in bnk $00
  212.                   BCS    ERROR             ;Carry is set on an error
  213.  
  214.    This is an example of an extended SmartPort call:
  215.  
  216.  
  217.    SP_EXT_CALL    JSR    DISPATCH          ;Call SmartPort command dispatcher
  218.                   DC     i1'CMDNUM+$40'    ;This specifies the ext cmd type
  219.                   DC     i4'CMDLIST'       ;Pointer to the parameter list
  220.                   BCS    ERROR             ;Carry is set on an error
  221.  
  222.    Page 121, Generic SmartPort calls:  Change occurrences of "Generic
  223.    SmartPort Calls" to "Standard and Extended SmartPort Calls" in the header
  224.    and the first sentence.  Refer to SmartPort Technical Note #2, SmartPort
  225.    Calls Updated, for updated information on the SmartPort STATUS call.
  226.  
  227.  
  228.    Page 122, Statcode = $00:  Change the function of bit 0 of the first
  229.    device status byte to:  "1 = Device currently open (character devices
  230.    only) or disk switched (block device only)."
  231.  
  232.  
  233.    Page 124:  SmartPort device types should be same as those documented in
  234.    SmartPort Technical Note #4, SmartPort Device Types.
  235.  
  236.  
  237.  
  238.    Page 125, SmartPort driver status:  See SmartPort Technical Note #2,
  239.    SmartPort Calls Updated, for the correct format of the status list for
  240.    unit 0, status code 0.
  241.  
  242.  
  243.    Vendors must request a Vendor ID Assignment from Developer Technical
  244.    Support before using a specific value in bytes two and three.
  245.  
  246.  
  247.    Page 125, Possible errors:  Add the following:
  248.  
  249.       $1F  No interrupt.  Interrupts not supported.
  250.       $2B  No write.  Disk write-protected.
  251.       $2F  Offline.  Disk off-line or no disk in drive.
  252.  
  253.    Page 126, ReadBlock:  Add a sentence at the end of the first paragraph
  254.    which reads, "On return, the X and Y registers indicate the number of
  255.    bytes transferred."
  256.  
  257.  
  258.    Page 131, Open:  The following changes apply for the CMDNUM:
  259.  
  260.                Standard call     Extended call
  261.      CMDNUM    $06               $46
  262.  
  263.  
  264.    Page 132, Read:  Add a sentence at the end of the first paragraph which
  265.    reads, "On return, the X and Y registers indicate the number of bytes
  266.    transferred."
  267.  
  268.  
  269.    Page 140, Figure 7-8, Disk-sector format:  Change to the following:
  270.  
  271.    ----------------------------------------------------------------------
  272.    |13      |F|D|A|9|T|S|S|F|A|D|A|F|1       |F|D|A|A|S|699     |4|D|A|F|
  273.    |5-Nibble|F|5|A|6|r|e|i|o|d|E|A|F|5-Nibble|F|5|A|D|e|GCR     | |E|A|F|
  274.    |SelfSync| | | | |a|c|d|r|r| | | |SelfSync| | | | |c|Nibbles |C| | | |
  275.    |Fields  | | | | |c|t|e|m|s| | | |Fields  | | | | |t|Fields  |h| | | |
  276.    |        | | | | |k|o| |a|L| | | |        | | | | |o|        |e| | | |
  277.    |        | | | | | |r| |t|R| | | |        | | | | |r|        |c| | | |
  278.    |        | | | | | | | | |C| | | |        | | | | | |        |k| | | |
  279.    |        | | | | | | | | | | | | |        | | | | | |        |s| | | |
  280.    |        | | | | | | | | | | | | |        | | | | | |        |u| | | |
  281.    |        | | | | | | | | | | | | |        | | | | | |        |m| | | |
  282.    ----------------------------------------------------------------------
  283.     A SelfSync Field is four 20 microsecond selfsync nibbles written as
  284.     a sequence of five 16 microsecond nibbles.
  285.  
  286.  
  287.    Page 140, ResetHook:  The Control code and Control list should be:
  288.  
  289.  
  290.       Control Code      Control list
  291.       ------------------------------------------------------------
  292.       $06               Count low byte          $04
  293.                         Count high byte         $00
  294.                         Hook reference number   $xx, $00, $00, $00
  295.       ------------------------------------------------------------
  296.  
  297.    Page 141, SetInterleave:  The Control code and Control list should be:
  298.  
  299.  
  300.      Control Code       Control list
  301.      -------------------------------------------------------------
  302.      $0A                Count low byte          $01
  303.                         Count high byte         $00
  304.                         Interleave              $01 to $0C
  305.      -------------------------------------------------------------
  306.  
  307.    Page 143, UniDiskStat:  The Status code and Status list should be:
  308.  
  309.     Status Code   Status list
  310.     --------------------------------------------
  311.     $05           Byte                      $04
  312.                   Soft error                $00
  313.                   Retries                   $xx
  314.                   A register after execute  $xx
  315.                   Y register after execute  $xx
  316.                   P register after execute  $xx
  317.                   Byte                      $xx
  318.     --------------------------------------------
  319.  
  320.    Page 152, Passing parameters to a ROM disk:  Add a sentence to the end of
  321.    the second paragraph which reads:  "These locations will not be preserved
  322.    between SmartPort calls."
  323.  
  324.  
  325.    Page 156, Table 7-6, SmartPort error codes:  Add the following error code:
  326.  
  327.  
  328.       Acc value    Error type      Description
  329.       ------------------------------------------------------------
  330.       $69          IOTERM          I/O terminated due to new line
  331.       ------------------------------------------------------------
  332.  
  333.    Page 166, Table 7-8, Standard command packet contents":
  334.  
  335.    Byte 3 descriptions should read "Byte 2 of param list."
  336.    Byte 4 descriptions should read "Byte 3 of param list."
  337.    Byte 5 descriptions should read "Byte 4 of param list."
  338.    Byte 6 descriptions should read "Byte 5 of param list."
  339.    Byte 7 descriptions should read "Byte 6 of param list."
  340.    Byte 8 descriptions should read "Byte 7 of param list."
  341.    Byte 9 descriptions should read "Byte 8 of param list."
  342.  
  343.  
  344. CHAPTER 8:  INTERRUPT-HANDLER FIRMWARE
  345.  
  346.    Page 184, Serial-port interrupt notification:  The last three paragraphs
  347.    should be replaced with this paragraph:  "The interrupt completion routine
  348.    executes as part of the firmware interrupt handler and must be run in that
  349.    environment.  The interrupt completion routine must preserve the DBR,
  350.    speed, 8-bit native mode, D register, stack pointer (or just use the
  351.    current stack), and MSLOT for proper operation. A/X/Y need not be
  352.    preserved."
  353.  
  354.  
  355. CHAPTER 9:  APPLE DESKTOP BUS MICROCONTROLLER
  356.  
  357.    Page 191, Sync, $07:  The first sentence should read: "This command
  358.    performs the three preceding commands in sequence."
  359.  
  360.    Page 194, Receive Bytes, $48:  The fourth sentence should read:  "The
  361.    second byte value is a combination of the device address in the high
  362.    nibble and the ADB command in the low nibble (see the Apple IIgs Hardware
  363.    Reference)."
  364.  
  365.  
  366. CHAPTER 10:  MOUSE FIRMWARE
  367.  
  368.    Page 201:  Mouse button positions should be changed as follows:
  369.  
  370.  
  371.    o   X data byte
  372.        If bit 7 = 0, then mouse button 1 is down.
  373.        If bit 7 = 1, then mouse button 1 is up.
  374.  
  375.    o   Y data byte
  376.        If bit 7 = 0, then mouse button 0 is down.
  377.        If bit 7 = 1, then mouse button 0 is up.
  378.  
  379.    Page 205, Figure 10-1, Position and status information:
  380.    Bit 7 description should be:  "Currently, button 0 is up/down (0/1)."
  381.    Bit 6 description should be:  "Previously, button 0 was up/down (0/1)."
  382.  
  383.  
  384. APPENDIX B:  FIRMWARE ID BYTES
  385.  
  386.    Page 223, Table B-2, Register bit information:  Change the table to show
  387.    that Bits 7-0 of the Y register hold the ROM version number, and the X
  388.    register is reserved.  In addition, the table description should read:
  389.    "The Y register contains the machine ID and the ROM version number.  The X
  390.    register is reserved."
  391.  
  392.    Page 249, COUT1:  In the third sentence, change the value of line feed
  393.    from $8C to $8A.
  394.  
  395.    Page 277, RDALTZP:  Change the comment to read:  "Bit 7 = 1 if alt zp
  396.    enabled."
  397.  
  398. APPENDIX D:  VECTORS
  399.  
  400.    Page 272:  At the end of the introductory paragraph, add "The vectors
  401.    TOWRITEBRAM through TOPRINTMSG8 must be called in eight-bit native mode."
  402.  
  403.    See Apple IIgs Technical Note #102, Various Vectors, for more information
  404.    about the TOBRAMSETUP vector.
  405.  
  406.  
  407. Further Reference:
  408. _____________________________________________________________________________
  409.  
  410.    o   Apple IIgs Firmware Reference
  411.    o   Apple IIgs Firmware Reference 1MB Apple IIgs Update
  412.    o   Apple IIgs Technical Note #50, Extended Serial Interface Handling
  413.    o   Apple IIgs Technical Note #102, Various Vectors
  414.    o   SmartPort Technical Note #2, SmartPort Calls Updated
  415.